feat(guardrails): send attached file references with llm-as-judge evaluation - #1082

Ready. uipath-platform 0.2.31 is published (UiPath/uipath-python#1895 merged); this branch is rebased onto main, requires uipath-platform>=0.2.31, relocked, and bumped to 0.18.9. 320 guardrail tests pass against the published SDK.

What

Agent-scope and LLM-scope LLM-as-Judge guardrails on low-code agents now forward the run's job attachments to the guardrails backend as references (id, fileName, mimeType), so the judge can evaluate what is in the file rather than its metadata.

• New agent/guardrails/attachment_refs.py projects state.inner_state.job_attachments into attachment references — no runtime feature flag: the runtime forwards references for every built-in guardrail and every file type whenever the run has attachments (the guardrail's appliesTo = Prompts is the only runtime-side opt-out), and the backend's EnableGuardrailLlmAsJudgeAttachments flag decides whether they are used at all and which validators and types it can inspect (today llm_as_judge, text/pdf/images). Backward compatible: a backend without attachment support ignores the extra property and header (UnmappedMemberHandling = Skip). It never raises: the low-code guardrail node re-raises everything, so a malformed entry must not kill the run.
• guardrail_nodes.py: the payload generator runs once per evaluation, evaluate_guardrail is offloaded with asyncio.to_thread, and a backend 400 on a request that carried attachments is retried text-only rather than terminating the run.

Out of scope by design: the coded-agent middleware and decorator flavors, and tool scope.

v2 — no SAS resolution in the runtime (commit 51374716)

The first version resolved each attachment to a signed URL via get_blob_file_access_uri_async and sent the URL. The backend now resolves ids itself through Orchestrator (UiPath/Agents#6256), so the runtime forwards references only: no Orchestrator round-trip per file, no credential on the wire, no URL redaction. 320 guardrail tests pass; ruff and ruff format clean; mypy clean in guardrail files (the remaining errors are pre-existing missing-extras imports in chat/_legacy and agent/advanced/code_interpreter.py).

Merge order: UiPath/uipath-python#1895 (merged, published as uipath-platform 0.2.31) first; this PR now depends on that release.

Review fixes (d9d57812)

• Tool scope excluded. _create_guardrail_node had no scope check and the tool node routes through it, so a tool-scope judge would have shipped file contents on every tool call. Now Agent and LLM scope only, per the product decision.
• A helix 400 on a request that carried attachments falls back to text-only instead of terminating the run — the backend rejected the file references, which is not the agent's fault. A 400 without attachments still propagates.
• File names are truncated to the API's 260-character ceiling before forwarding.
• Dropped metadata["payload"]["attachments"]: nothing consumed it (the Python side creates no evaluation span for built-in guardrails; helix's span already records attachments) and it was never cleared across turns.

Scope selector (06a64b0c)

The judge guardrail gained an optional appliesTo parameter (Prompts / Files / Both) in UiPath/Agents#6256. The backend gates on it as well, but only after the SAS urls are resolved, so reading it here is what actually saves an Orchestrator round-trip per file on a prompts-only guardrail.

Absent, unrecognized, or unreadable keeps files in scope, matching the backend default of Both — silently stopping file scanning for a guardrail whose author never asked for that is the worse direction. The parameter id is matched case-insensitively, as the backend matches it.

Notes for reviewers

attachment_refs.py never raises. The low-code guardrail node re-raises everything it sees, which terminates the agent run — so a transient Orchestrator failure must never escape. Gated on appliesTo only; no feature flag, validator or type filter on the runtime side — the backend flag is the single kill switch.

Two pre-existing bugs fixed along the way, both with regression tests: the payload generator ran twice per evaluation, and the synchronous evaluate_guardrail blocked the event loop (now asyncio.to_thread).

Out of scope by design: the coded-agent middleware and decorator flavors.

Test plan

tests/agent/guardrails/ — 305 passed (baseline 279). tests/cli/ 55, tests/guardrails/ 253 (coded flavors, untouched). ruff, ruff format, mypy (touched files) clean.

Depends on: UiPath/uipath-python#1895 · pairs with UiPath/Agents#6256

🤖 Generated with Claude Code